<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>The numpy.ma module &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>
    <script type="text/javascript" src="../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../about.html" >
    <link rel="index" title="Index" href="../genindex.html" >
    <link rel="search" title="Search" href="../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../index.html" >
    <link rel="up" title="Masked arrays" href="maskedarray.html" >
    <link rel="next" title="numpy.ma.array" href="generated/numpy.ma.array.html" >
    <link rel="prev" title="Masked arrays" href="maskedarray.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../index.html">
      <img border=0 alt="NumPy" src="../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="index.html" >NumPy Reference</a></li>
          <li class="active"><a href="arrays.html" >Array objects</a></li>
          <li class="active"><a href="maskedarray.html" accesskey="U">Masked arrays</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="generated/numpy.ma.array.html" title="numpy.ma.array"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="maskedarray.html" title="Masked arrays"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../contents.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">The <code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy.ma</span></code> module</a><ul>
<li><a class="reference internal" href="#rationale">Rationale</a></li>
<li><a class="reference internal" href="#what-is-a-masked-array">What is a masked array?</a></li>
<li><a class="reference internal" href="#id1">The <code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy.ma</span></code> module</a></li>
</ul>
</li>
<li><a class="reference internal" href="#using-numpy-ma">Using numpy.ma</a><ul>
<li><a class="reference internal" href="#constructing-masked-arrays">Constructing masked arrays</a><ul>
</ul>
</li>
<li><a class="reference internal" href="#accessing-the-data">Accessing the data</a></li>
<li><a class="reference internal" href="#accessing-the-mask">Accessing the mask</a></li>
<li><a class="reference internal" href="#accessing-only-the-valid-entries">Accessing only the valid entries</a></li>
<li><a class="reference internal" href="#modifying-the-mask">Modifying the mask</a><ul>
<li><a class="reference internal" href="#masking-an-entry">Masking an entry</a></li>
<li><a class="reference internal" href="#unmasking-an-entry">Unmasking an entry</a></li>
</ul>
</li>
<li><a class="reference internal" href="#indexing-and-slicing">Indexing and slicing</a></li>
<li><a class="reference internal" href="#operations-on-masked-arrays">Operations on masked arrays</a></li>
</ul>
</li>
<li><a class="reference internal" href="#examples">Examples</a><ul>
<li><a class="reference internal" href="#data-with-a-given-value-representing-missing-data">Data with a given value representing missing data</a></li>
<li><a class="reference internal" href="#filling-in-the-missing-data">Filling in the missing data</a></li>
<li><a class="reference internal" href="#numerical-operations">Numerical operations</a></li>
<li><a class="reference internal" href="#ignoring-extreme-values">Ignoring extreme values</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="maskedarray.html"
                        title="previous chapter">Masked arrays</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="generated/numpy.ma.array.html"
                        title="next chapter">numpy.ma.array</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <span class="target" id="module-numpy.ma"><span id="maskedarray-generic"></span></span><div class="section" id="the-numpy-ma-module">
<h1>The <a class="reference internal" href="#module-numpy.ma" title="numpy.ma"><code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy.ma</span></code></a> module<a class="headerlink" href="#the-numpy-ma-module" title="Permalink to this headline">¶</a></h1>
<div class="section" id="rationale">
<h2>Rationale<a class="headerlink" href="#rationale" title="Permalink to this headline">¶</a></h2>
<p>Masked arrays are arrays that may have missing or invalid entries.
The <a class="reference internal" href="#module-numpy.ma" title="numpy.ma"><code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy.ma</span></code></a> module provides a nearly work-alike replacement for numpy
that supports data arrays with masks.</p>
</div>
<div class="section" id="what-is-a-masked-array">
<h2>What is a masked array?<a class="headerlink" href="#what-is-a-masked-array" title="Permalink to this headline">¶</a></h2>
<p>In many circumstances, datasets can be incomplete or tainted by the presence
of invalid data. For example, a sensor may have failed to record a data, or
recorded an invalid value. The <a class="reference internal" href="#module-numpy.ma" title="numpy.ma"><code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy.ma</span></code></a> module provides a convenient
way to address this issue, by introducing masked arrays.</p>
<p>A masked array is the combination of a standard <a class="reference internal" href="generated/numpy.ndarray.html#numpy.ndarray" title="numpy.ndarray"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.ndarray</span></code></a> and a
mask. A mask is either <a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.nomask" title="numpy.ma.nomask"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nomask</span></code></a>, indicating that no value of the
associated array is invalid, or an array of booleans that determines for each
element of the associated array whether the value is valid or not. When an
element of the mask is <code class="docutils literal notranslate"><span class="pre">False</span></code>, the corresponding element of the associated
array is valid and is said to be unmasked. When an element of the mask is
<code class="docutils literal notranslate"><span class="pre">True</span></code>, the corresponding element of the associated array is said to be
masked (invalid).</p>
<p>The package ensures that masked entries are not used in computations.</p>
<p>As an illustration, let’s consider the following dataset:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">numpy.ma</span> <span class="k">as</span> <span class="nn">ma</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="mi">5</span><span class="p">])</span>
</pre></div>
</div>
<p>We wish to mark the fourth entry as invalid. The easiest is to create a masked
array:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mx</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">masked_array</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">mask</span><span class="o">=</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">])</span>
</pre></div>
</div>
<p>We can now compute the mean of the dataset, without taking the invalid data
into account:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mx</span><span class="o">.</span><span class="n">mean</span><span class="p">()</span>
<span class="go">2.75</span>
</pre></div>
</div>
</div>
<div class="section" id="id1">
<h2>The <a class="reference internal" href="#module-numpy.ma" title="numpy.ma"><code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy.ma</span></code></a> module<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h2>
<p>The main feature of the <a class="reference internal" href="#module-numpy.ma" title="numpy.ma"><code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy.ma</span></code></a> module is the <a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.MaskedArray" title="numpy.ma.MaskedArray"><code class="xref py py-class docutils literal notranslate"><span class="pre">MaskedArray</span></code></a>
class, which is a subclass of <a class="reference internal" href="generated/numpy.ndarray.html#numpy.ndarray" title="numpy.ndarray"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.ndarray</span></code></a>. The class, its
attributes and methods are described in more details in the
<a class="reference internal" href="maskedarray.baseclass.html#maskedarray-baseclass"><span class="std std-ref">MaskedArray class</span></a> section.</p>
<p>The <a class="reference internal" href="#module-numpy.ma" title="numpy.ma"><code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy.ma</span></code></a> module can be used as an addition to <a class="reference internal" href="index.html#module-numpy" title="numpy"><code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">numpy.ma</span> <span class="k">as</span> <span class="nn">ma</span>
</pre></div>
</div>
<p>To create an array with the second element invalid, we would do:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">y</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="n">mask</span> <span class="o">=</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">])</span>
</pre></div>
</div>
<p>To create a masked array where all values close to 1.e20 are invalid, we would
do:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">z</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">masked_values</span><span class="p">([</span><span class="mf">1.0</span><span class="p">,</span> <span class="mf">1.e20</span><span class="p">,</span> <span class="mf">3.0</span><span class="p">,</span> <span class="mf">4.0</span><span class="p">],</span> <span class="mf">1.e20</span><span class="p">)</span>
</pre></div>
</div>
<p>For a complete discussion of creation methods for masked arrays please see
section <a class="reference internal" href="#maskedarray-generic-constructing"><span class="std std-ref">Constructing masked arrays</span></a>.</p>
</div>
</div>
<div class="section" id="using-numpy-ma">
<h1>Using numpy.ma<a class="headerlink" href="#using-numpy-ma" title="Permalink to this headline">¶</a></h1>
<div class="section" id="constructing-masked-arrays">
<span id="maskedarray-generic-constructing"></span><h2>Constructing masked arrays<a class="headerlink" href="#constructing-masked-arrays" title="Permalink to this headline">¶</a></h2>
<p>There are several ways to construct a masked array.</p>
<ul>
<li><p>A first possibility is to directly invoke the <a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.MaskedArray" title="numpy.ma.MaskedArray"><code class="xref py py-class docutils literal notranslate"><span class="pre">MaskedArray</span></code></a> class.</p></li>
<li><p>A second possibility is to use the two masked array constructors,
<a class="reference internal" href="generated/numpy.ma.array.html#numpy.ma.array" title="numpy.ma.array"><code class="xref py py-func docutils literal notranslate"><span class="pre">array</span></code></a> and <a class="reference internal" href="generated/numpy.ma.masked_array.html#numpy.ma.masked_array" title="numpy.ma.masked_array"><code class="xref py py-func docutils literal notranslate"><span class="pre">masked_array</span></code></a>.</p>
<table class="longtable docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 90%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="generated/numpy.ma.array.html#numpy.ma.array" title="numpy.ma.array"><code class="xref py py-obj docutils literal notranslate"><span class="pre">array</span></code></a>(data[, dtype, copy, order, mask, …])</p></td>
<td><p>An array class with possibly masked values.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="generated/numpy.ma.masked_array.html#numpy.ma.masked_array" title="numpy.ma.masked_array"><code class="xref py py-obj docutils literal notranslate"><span class="pre">masked_array</span></code></a></p></td>
<td><p>alias of <code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.ma.core.MaskedArray</span></code></p></td>
</tr>
</tbody>
</table>
</li>
<li><p>A third option is to take the view of an existing array. In that case, the
mask of the view is set to <a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.nomask" title="numpy.ma.nomask"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nomask</span></code></a> if the array has no named fields,
or an array of boolean with the same structure as the array otherwise.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="o">.</span><span class="n">view</span><span class="p">(</span><span class="n">ma</span><span class="o">.</span><span class="n">MaskedArray</span><span class="p">)</span>
<span class="go">masked_array(data=[1, 2, 3],</span>
<span class="go">             mask=False,</span>
<span class="go">       fill_value=999999)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([(</span><span class="mi">1</span><span class="p">,</span> <span class="mf">1.</span><span class="p">),</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mf">2.</span><span class="p">)],</span> <span class="n">dtype</span><span class="o">=</span><span class="p">[(</span><span class="s1">&#39;a&#39;</span><span class="p">,</span><span class="nb">int</span><span class="p">),</span> <span class="p">(</span><span class="s1">&#39;b&#39;</span><span class="p">,</span> <span class="nb">float</span><span class="p">)])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="o">.</span><span class="n">view</span><span class="p">(</span><span class="n">ma</span><span class="o">.</span><span class="n">MaskedArray</span><span class="p">)</span>
<span class="go">masked_array(data=[(1, 1.0), (2, 2.0)],</span>
<span class="go">             mask=[(False, False), (False, False)],</span>
<span class="go">       fill_value=(999999, 1.e+20),</span>
<span class="go">            dtype=[(&#39;a&#39;, &#39;&lt;i8&#39;), (&#39;b&#39;, &#39;&lt;f8&#39;)])</span>
</pre></div>
</div>
</li>
<li><p>Yet another possibility is to use any of the following functions:</p>
<table class="longtable docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 90%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="generated/numpy.ma.asarray.html#numpy.ma.asarray" title="numpy.ma.asarray"><code class="xref py py-obj docutils literal notranslate"><span class="pre">asarray</span></code></a>(a[, dtype, order])</p></td>
<td><p>Convert the input to a masked array of the given data-type.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="generated/numpy.ma.asanyarray.html#numpy.ma.asanyarray" title="numpy.ma.asanyarray"><code class="xref py py-obj docutils literal notranslate"><span class="pre">asanyarray</span></code></a>(a[, dtype])</p></td>
<td><p>Convert the input to a masked array, conserving subclasses.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="generated/numpy.ma.fix_invalid.html#numpy.ma.fix_invalid" title="numpy.ma.fix_invalid"><code class="xref py py-obj docutils literal notranslate"><span class="pre">fix_invalid</span></code></a>(a[, mask, copy, fill_value])</p></td>
<td><p>Return input with invalid data masked and replaced by a fill value.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="generated/numpy.ma.masked_equal.html#numpy.ma.masked_equal" title="numpy.ma.masked_equal"><code class="xref py py-obj docutils literal notranslate"><span class="pre">masked_equal</span></code></a>(x, value[, copy])</p></td>
<td><p>Mask an array where equal to a given value.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="generated/numpy.ma.masked_greater.html#numpy.ma.masked_greater" title="numpy.ma.masked_greater"><code class="xref py py-obj docutils literal notranslate"><span class="pre">masked_greater</span></code></a>(x, value[, copy])</p></td>
<td><p>Mask an array where greater than a given value.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="generated/numpy.ma.masked_greater_equal.html#numpy.ma.masked_greater_equal" title="numpy.ma.masked_greater_equal"><code class="xref py py-obj docutils literal notranslate"><span class="pre">masked_greater_equal</span></code></a>(x, value[, copy])</p></td>
<td><p>Mask an array where greater than or equal to a given value.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="generated/numpy.ma.masked_inside.html#numpy.ma.masked_inside" title="numpy.ma.masked_inside"><code class="xref py py-obj docutils literal notranslate"><span class="pre">masked_inside</span></code></a>(x, v1, v2[, copy])</p></td>
<td><p>Mask an array inside a given interval.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="generated/numpy.ma.masked_invalid.html#numpy.ma.masked_invalid" title="numpy.ma.masked_invalid"><code class="xref py py-obj docutils literal notranslate"><span class="pre">masked_invalid</span></code></a>(a[, copy])</p></td>
<td><p>Mask an array where invalid values occur (NaNs or infs).</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="generated/numpy.ma.masked_less.html#numpy.ma.masked_less" title="numpy.ma.masked_less"><code class="xref py py-obj docutils literal notranslate"><span class="pre">masked_less</span></code></a>(x, value[, copy])</p></td>
<td><p>Mask an array where less than a given value.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="generated/numpy.ma.masked_less_equal.html#numpy.ma.masked_less_equal" title="numpy.ma.masked_less_equal"><code class="xref py py-obj docutils literal notranslate"><span class="pre">masked_less_equal</span></code></a>(x, value[, copy])</p></td>
<td><p>Mask an array where less than or equal to a given value.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="generated/numpy.ma.masked_not_equal.html#numpy.ma.masked_not_equal" title="numpy.ma.masked_not_equal"><code class="xref py py-obj docutils literal notranslate"><span class="pre">masked_not_equal</span></code></a>(x, value[, copy])</p></td>
<td><p>Mask an array where <em class="xref py py-obj">not</em> equal to a given value.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="generated/numpy.ma.masked_object.html#numpy.ma.masked_object" title="numpy.ma.masked_object"><code class="xref py py-obj docutils literal notranslate"><span class="pre">masked_object</span></code></a>(x, value[, copy, shrink])</p></td>
<td><p>Mask the array <em class="xref py py-obj">x</em> where the data are exactly equal to value.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="generated/numpy.ma.masked_outside.html#numpy.ma.masked_outside" title="numpy.ma.masked_outside"><code class="xref py py-obj docutils literal notranslate"><span class="pre">masked_outside</span></code></a>(x, v1, v2[, copy])</p></td>
<td><p>Mask an array outside a given interval.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="generated/numpy.ma.masked_values.html#numpy.ma.masked_values" title="numpy.ma.masked_values"><code class="xref py py-obj docutils literal notranslate"><span class="pre">masked_values</span></code></a>(x, value[, rtol, atol, copy, …])</p></td>
<td><p>Mask using floating point equality.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="generated/numpy.ma.masked_where.html#numpy.ma.masked_where" title="numpy.ma.masked_where"><code class="xref py py-obj docutils literal notranslate"><span class="pre">masked_where</span></code></a>(condition, a[, copy])</p></td>
<td><p>Mask an array where a condition is met.</p></td>
</tr>
</tbody>
</table>
</li>
</ul>
</div>
<div class="section" id="accessing-the-data">
<h2>Accessing the data<a class="headerlink" href="#accessing-the-data" title="Permalink to this headline">¶</a></h2>
<p>The underlying data of a masked array can be accessed in several ways:</p>
<ul class="simple">
<li><p>through the <a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.MaskedArray.data" title="numpy.ma.MaskedArray.data"><code class="xref py py-attr docutils literal notranslate"><span class="pre">data</span></code></a> attribute. The output is a view of the
array as a <a class="reference internal" href="generated/numpy.ndarray.html#numpy.ndarray" title="numpy.ndarray"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.ndarray</span></code></a> or one of its subclasses, depending on the
type of the underlying data at the masked array creation.</p></li>
<li><p>through the <a class="reference internal" href="generated/numpy.ma.MaskedArray.__array__.html#numpy.ma.MaskedArray.__array__" title="numpy.ma.MaskedArray.__array__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__array__</span></code></a> method. The output is then a
<a class="reference internal" href="generated/numpy.ndarray.html#numpy.ndarray" title="numpy.ndarray"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.ndarray</span></code></a>.</p></li>
<li><p>by directly taking a view of the masked array as a <a class="reference internal" href="generated/numpy.ndarray.html#numpy.ndarray" title="numpy.ndarray"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.ndarray</span></code></a>
or one of its subclass (which is actually what using the
<a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.MaskedArray.data" title="numpy.ma.MaskedArray.data"><code class="xref py py-attr docutils literal notranslate"><span class="pre">data</span></code></a> attribute does).</p></li>
<li><p>by using the <a class="reference internal" href="generated/numpy.ma.getdata.html#numpy.ma.getdata" title="numpy.ma.getdata"><code class="xref py py-func docutils literal notranslate"><span class="pre">getdata</span></code></a> function.</p></li>
</ul>
<p>None of these methods is completely satisfactory if some entries have been
marked as invalid. As a general rule, where a representation of the array is
required without any masked entries, it is recommended to fill the array with
the <a class="reference internal" href="generated/numpy.ma.filled.html#numpy.ma.filled" title="numpy.ma.filled"><code class="xref py py-meth docutils literal notranslate"><span class="pre">filled</span></code></a> method.</p>
</div>
<div class="section" id="accessing-the-mask">
<h2>Accessing the mask<a class="headerlink" href="#accessing-the-mask" title="Permalink to this headline">¶</a></h2>
<p>The mask of a masked array is accessible through its <a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.MaskedArray.mask" title="numpy.ma.MaskedArray.mask"><code class="xref py py-attr docutils literal notranslate"><span class="pre">mask</span></code></a>
attribute. We must keep in mind that a <code class="docutils literal notranslate"><span class="pre">True</span></code> entry in the mask indicates an
<em>invalid</em> data.</p>
<p>Another possibility is to use the <a class="reference internal" href="generated/numpy.ma.getmask.html#numpy.ma.getmask" title="numpy.ma.getmask"><code class="xref py py-func docutils literal notranslate"><span class="pre">getmask</span></code></a> and <a class="reference internal" href="generated/numpy.ma.getmaskarray.html#numpy.ma.getmaskarray" title="numpy.ma.getmaskarray"><code class="xref py py-func docutils literal notranslate"><span class="pre">getmaskarray</span></code></a>
functions. <code class="xref py py-func docutils literal notranslate"><span class="pre">getmask(x)</span></code> outputs the mask of <code class="docutils literal notranslate"><span class="pre">x</span></code> if <code class="docutils literal notranslate"><span class="pre">x</span></code> is a masked
array, and the special value <a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.nomask" title="numpy.ma.nomask"><code class="xref py py-data docutils literal notranslate"><span class="pre">nomask</span></code></a> otherwise. <code class="xref py py-func docutils literal notranslate"><span class="pre">getmaskarray(x)</span></code>
outputs the mask of <code class="docutils literal notranslate"><span class="pre">x</span></code> if <code class="docutils literal notranslate"><span class="pre">x</span></code> is a masked array. If <code class="docutils literal notranslate"><span class="pre">x</span></code> has no invalid
entry or is not a masked array, the function outputs  a boolean array of
<code class="docutils literal notranslate"><span class="pre">False</span></code> with as many elements as <code class="docutils literal notranslate"><span class="pre">x</span></code>.</p>
</div>
<div class="section" id="accessing-only-the-valid-entries">
<h2>Accessing only the valid entries<a class="headerlink" href="#accessing-only-the-valid-entries" title="Permalink to this headline">¶</a></h2>
<p>To retrieve only the valid entries, we can use the inverse of the mask as an
index. The inverse of the mask can be calculated with the
<a class="reference internal" href="generated/numpy.logical_not.html#numpy.logical_not" title="numpy.logical_not"><code class="xref py py-func docutils literal notranslate"><span class="pre">numpy.logical_not</span></code></a> function or simply with the <code class="docutils literal notranslate"><span class="pre">~</span></code> operator:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">array</span><span class="p">([[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">],</span> <span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">]],</span> <span class="n">mask</span><span class="o">=</span><span class="p">[[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">],</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">]])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="p">[</span><span class="o">~</span><span class="n">x</span><span class="o">.</span><span class="n">mask</span><span class="p">]</span>
<span class="go">masked_array(data=[1, 4],</span>
<span class="go">             mask=[False, False],</span>
<span class="go">       fill_value=999999)</span>
</pre></div>
</div>
<p>Another way to retrieve the valid data is to use the <a class="reference internal" href="generated/numpy.ma.compressed.html#numpy.ma.compressed" title="numpy.ma.compressed"><code class="xref py py-meth docutils literal notranslate"><span class="pre">compressed</span></code></a>
method, which returns a one-dimensional <a class="reference internal" href="generated/numpy.ndarray.html#numpy.ndarray" title="numpy.ndarray"><code class="xref py py-class docutils literal notranslate"><span class="pre">ndarray</span></code></a> (or one of its
subclasses, depending on the value of the <a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.MaskedArray.baseclass" title="numpy.ma.MaskedArray.baseclass"><code class="xref py py-attr docutils literal notranslate"><span class="pre">baseclass</span></code></a>
attribute):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="o">.</span><span class="n">compressed</span><span class="p">()</span>
<span class="go">array([1, 4])</span>
</pre></div>
</div>
<p>Note that the output of <a class="reference internal" href="generated/numpy.ma.compressed.html#numpy.ma.compressed" title="numpy.ma.compressed"><code class="xref py py-meth docutils literal notranslate"><span class="pre">compressed</span></code></a> is always 1D.</p>
</div>
<div class="section" id="modifying-the-mask">
<h2>Modifying the mask<a class="headerlink" href="#modifying-the-mask" title="Permalink to this headline">¶</a></h2>
<div class="section" id="masking-an-entry">
<h3>Masking an entry<a class="headerlink" href="#masking-an-entry" title="Permalink to this headline">¶</a></h3>
<p>The recommended way to mark one or several specific entries of a masked array
as invalid is to assign the special value <a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.masked" title="numpy.ma.masked"><code class="xref py py-attr docutils literal notranslate"><span class="pre">masked</span></code></a> to them:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">masked</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span>
<span class="go">masked_array(data=[--, 2, 3],</span>
<span class="go">             mask=[ True, False, False],</span>
<span class="go">       fill_value=999999)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">y</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">array</span><span class="p">([[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="p">[</span><span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">],</span> <span class="p">[</span><span class="mi">7</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">9</span><span class="p">]])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">y</span><span class="p">[(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">)]</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">masked</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">y</span>
<span class="go">masked_array(</span>
<span class="go">  data=[[1, --, 3],</span>
<span class="go">        [4, 5, --],</span>
<span class="go">        [--, 8, 9]],</span>
<span class="go">  mask=[[False,  True, False],</span>
<span class="go">        [False, False,  True],</span>
<span class="go">        [ True, False, False]],</span>
<span class="go">  fill_value=999999)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">z</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">z</span><span class="p">[:</span><span class="o">-</span><span class="mi">2</span><span class="p">]</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">masked</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">z</span>
<span class="go">masked_array(data=[--, --, 3, 4],</span>
<span class="go">             mask=[ True,  True, False, False],</span>
<span class="go">       fill_value=999999)</span>
</pre></div>
</div>
<p>A second possibility is to modify the <a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.MaskedArray.mask" title="numpy.ma.MaskedArray.mask"><code class="xref py py-attr docutils literal notranslate"><span class="pre">mask</span></code></a> directly,
but this usage is discouraged.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>When creating a new masked array with a simple, non-structured datatype,
the mask is initially set to the special value <a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.nomask" title="numpy.ma.nomask"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nomask</span></code></a>, that
corresponds roughly to the boolean <code class="docutils literal notranslate"><span class="pre">False</span></code>. Trying to set an element of
<a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.nomask" title="numpy.ma.nomask"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nomask</span></code></a> will fail with a <a class="reference external" href="https://docs.python.org/dev/library/exceptions.html#TypeError" title="(in Python v3.9)"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> exception, as a boolean
does not support item assignment.</p>
</div>
<p>All the entries of an array can be masked at once by assigning <code class="docutils literal notranslate"><span class="pre">True</span></code> to the
mask:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="n">mask</span><span class="o">=</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="o">.</span><span class="n">mask</span> <span class="o">=</span> <span class="kc">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span>
<span class="go">masked_array(data=[--, --, --],</span>
<span class="go">             mask=[ True,  True,  True],</span>
<span class="go">       fill_value=999999,</span>
<span class="go">            dtype=int64)</span>
</pre></div>
</div>
<p>Finally, specific entries can be masked and/or unmasked by assigning to the
mask a sequence of booleans:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="o">.</span><span class="n">mask</span> <span class="o">=</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span>
<span class="go">masked_array(data=[1, --, 3],</span>
<span class="go">             mask=[False,  True, False],</span>
<span class="go">       fill_value=999999)</span>
</pre></div>
</div>
</div>
<div class="section" id="unmasking-an-entry">
<h3>Unmasking an entry<a class="headerlink" href="#unmasking-an-entry" title="Permalink to this headline">¶</a></h3>
<p>To unmask one or several specific entries, we can just assign one or several
new valid values to them:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="n">mask</span><span class="o">=</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span>
<span class="go">masked_array(data=[1, 2, --],</span>
<span class="go">             mask=[False, False,  True],</span>
<span class="go">       fill_value=999999)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="mi">5</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span>
<span class="go">masked_array(data=[1, 2, 5],</span>
<span class="go">             mask=[False, False, False],</span>
<span class="go">       fill_value=999999)</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Unmasking an entry by direct assignment will silently fail if the masked
array has a <em>hard</em> mask, as shown by the <code class="xref py py-attr docutils literal notranslate"><span class="pre">hardmask</span></code> attribute. This
feature was introduced to prevent overwriting the mask. To force the
unmasking of an entry where the array has a hard mask, the mask must first
to be softened using the <a class="reference internal" href="generated/numpy.ma.soften_mask.html#numpy.ma.soften_mask" title="numpy.ma.soften_mask"><code class="xref py py-meth docutils literal notranslate"><span class="pre">soften_mask</span></code></a> method before the allocation.
It can be re-hardened with <a class="reference internal" href="generated/numpy.ma.harden_mask.html#numpy.ma.harden_mask" title="numpy.ma.harden_mask"><code class="xref py py-meth docutils literal notranslate"><span class="pre">harden_mask</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="n">mask</span><span class="o">=</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">],</span> <span class="n">hard_mask</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span>
<span class="go">masked_array(data=[1, 2, --],</span>
<span class="go">             mask=[False, False,  True],</span>
<span class="go">       fill_value=999999)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="mi">5</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span>
<span class="go">masked_array(data=[1, 2, --],</span>
<span class="go">             mask=[False, False,  True],</span>
<span class="go">       fill_value=999999)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="o">.</span><span class="n">soften_mask</span><span class="p">()</span>
<span class="go">masked_array(data=[1, 2, --],</span>
<span class="go">             mask=[False, False,  True],</span>
<span class="go">       fill_value=999999)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="mi">5</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span>
<span class="go">masked_array(data=[1, 2, 5],</span>
<span class="go">             mask=[False, False, False],</span>
<span class="go">       fill_value=999999)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="o">.</span><span class="n">harden_mask</span><span class="p">()</span>
<span class="go">masked_array(data=[1, 2, 5],</span>
<span class="go">             mask=[False, False, False],</span>
<span class="go">       fill_value=999999)</span>
</pre></div>
</div>
</div>
<p>To unmask all masked entries of a masked array (provided the mask isn’t a hard
mask), the simplest solution is to assign the constant <a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.nomask" title="numpy.ma.nomask"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nomask</span></code></a> to the
mask:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="n">mask</span><span class="o">=</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span>
<span class="go">masked_array(data=[1, 2, --],</span>
<span class="go">             mask=[False, False,  True],</span>
<span class="go">       fill_value=999999)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="o">.</span><span class="n">mask</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">nomask</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span>
<span class="go">masked_array(data=[1, 2, 3],</span>
<span class="go">             mask=[False, False, False],</span>
<span class="go">       fill_value=999999)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="indexing-and-slicing">
<h2>Indexing and slicing<a class="headerlink" href="#indexing-and-slicing" title="Permalink to this headline">¶</a></h2>
<p>As a <a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.MaskedArray" title="numpy.ma.MaskedArray"><code class="xref py py-class docutils literal notranslate"><span class="pre">MaskedArray</span></code></a> is a subclass of <a class="reference internal" href="generated/numpy.ndarray.html#numpy.ndarray" title="numpy.ndarray"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.ndarray</span></code></a>, it inherits
its mechanisms for indexing and slicing.</p>
<p>When accessing a single entry of a masked array with no named fields, the
output is either a scalar (if the corresponding entry of the mask is
<code class="docutils literal notranslate"><span class="pre">False</span></code>) or the special value <a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.masked" title="numpy.ma.masked"><code class="xref py py-attr docutils literal notranslate"><span class="pre">masked</span></code></a> (if the corresponding entry of
the mask is <code class="docutils literal notranslate"><span class="pre">True</span></code>):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="n">mask</span><span class="o">=</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="go">1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>
<span class="go">masked</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="ow">is</span> <span class="n">ma</span><span class="o">.</span><span class="n">masked</span>
<span class="go">True</span>
</pre></div>
</div>
<p>If the masked array has named fields, accessing a single entry returns a
<code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.void</span></code> object if none of the fields are masked, or a 0d masked
array with the same dtype as the initial array if at least one of the fields
is masked.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">y</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">masked_array</span><span class="p">([(</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">)],</span>
<span class="gp">... </span>               <span class="n">mask</span><span class="o">=</span><span class="p">[(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">)],</span>
<span class="gp">... </span>              <span class="n">dtype</span><span class="o">=</span><span class="p">[(</span><span class="s1">&#39;a&#39;</span><span class="p">,</span> <span class="nb">int</span><span class="p">),</span> <span class="p">(</span><span class="s1">&#39;b&#39;</span><span class="p">,</span> <span class="nb">int</span><span class="p">)])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">y</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="go">(1, 2)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">y</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>
<span class="go">(3, --)</span>
</pre></div>
</div>
<p>When accessing a slice, the output is a masked array whose
<a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.MaskedArray.data" title="numpy.ma.MaskedArray.data"><code class="xref py py-attr docutils literal notranslate"><span class="pre">data</span></code></a> attribute is a view of the original data, and whose
mask is either <a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.nomask" title="numpy.ma.nomask"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nomask</span></code></a> (if there was no invalid entries in the original
array) or a view of the corresponding slice of the original mask. The view is
required to ensure propagation of any modification of the mask to the original.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">],</span> <span class="n">mask</span><span class="o">=</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">mx</span> <span class="o">=</span> <span class="n">x</span><span class="p">[:</span><span class="mi">3</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">mx</span>
<span class="go">masked_array(data=[1, --, 3],</span>
<span class="go">             mask=[False,  True, False],</span>
<span class="go">       fill_value=999999)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">mx</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">mx</span>
<span class="go">masked_array(data=[1, -1, 3],</span>
<span class="go">             mask=[False, False, False],</span>
<span class="go">       fill_value=999999)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="o">.</span><span class="n">mask</span>
<span class="go">array([False, False, False, False,  True])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="o">.</span><span class="n">data</span>
<span class="go">array([ 1, -1,  3,  4,  5])</span>
</pre></div>
</div>
<p>Accessing a field of a masked array with structured datatype returns a
<a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.MaskedArray" title="numpy.ma.MaskedArray"><code class="xref py py-class docutils literal notranslate"><span class="pre">MaskedArray</span></code></a>.</p>
</div>
<div class="section" id="operations-on-masked-arrays">
<h2>Operations on masked arrays<a class="headerlink" href="#operations-on-masked-arrays" title="Permalink to this headline">¶</a></h2>
<p>Arithmetic and comparison operations are supported by masked arrays.
As much as possible, invalid entries of a masked array are not processed,
meaning that the corresponding <code class="xref py py-attr docutils literal notranslate"><span class="pre">data</span></code> entries <em>should</em> be the same
before and after the operation.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>We need to stress that this behavior may not be systematic, that masked
data may be affected by the operation in some cases and therefore users
should not rely on this data remaining unchanged.</p>
</div>
<p>The <a class="reference internal" href="#module-numpy.ma" title="numpy.ma"><code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy.ma</span></code></a> module comes with a specific implementation of most
ufuncs. Unary and binary functions that have a validity domain (such as
<a class="reference internal" href="generated/numpy.log.html#numpy.log" title="numpy.log"><code class="xref py py-func docutils literal notranslate"><span class="pre">log</span></code></a> or <a class="reference internal" href="generated/numpy.divide.html#numpy.divide" title="numpy.divide"><code class="xref py py-func docutils literal notranslate"><span class="pre">divide</span></code></a>) return the <a class="reference internal" href="maskedarray.baseclass.html#numpy.ma.masked" title="numpy.ma.masked"><code class="xref py py-data docutils literal notranslate"><span class="pre">masked</span></code></a>
constant whenever the input is masked or falls outside the validity domain:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">ma</span><span class="o">.</span><span class="n">log</span><span class="p">([</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">])</span>
<span class="go">masked_array(data=[--, --, 0.0, 0.6931471805599453],</span>
<span class="go">             mask=[ True,  True, False, False],</span>
<span class="go">       fill_value=1e+20)</span>
</pre></div>
</div>
<p>Masked arrays also support standard numpy ufuncs. The output is then a masked
array. The result of a unary ufunc is masked wherever the input is masked. The
result of a binary ufunc is masked wherever any of the input is masked. If the
ufunc also returns the optional context output (a 3-element tuple containing
the name of the ufunc, its arguments and its domain), the context is processed
and entries of the output masked array are masked wherever the corresponding
input fall outside the validity domain:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="n">mask</span><span class="o">=</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
<span class="go">masked_array(data=[--, 0.0, --, 0.6931471805599453, --],</span>
<span class="go">             mask=[ True, False,  True, False,  True],</span>
<span class="go">       fill_value=1e+20)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="examples">
<h1>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h1>
<div class="section" id="data-with-a-given-value-representing-missing-data">
<h2>Data with a given value representing missing data<a class="headerlink" href="#data-with-a-given-value-representing-missing-data" title="Permalink to this headline">¶</a></h2>
<p>Let’s consider a list of elements, <code class="docutils literal notranslate"><span class="pre">x</span></code>, where values of -9999. represent
missing data. We wish to compute the average value of the data and the vector
of anomalies (deviations from the average):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">numpy.ma</span> <span class="k">as</span> <span class="nn">ma</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="p">[</span><span class="mf">0.</span><span class="p">,</span><span class="mf">1.</span><span class="p">,</span><span class="o">-</span><span class="mf">9999.</span><span class="p">,</span><span class="mf">3.</span><span class="p">,</span><span class="mf">4.</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">mx</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">masked_values</span> <span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="o">-</span><span class="mf">9999.</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">mx</span><span class="o">.</span><span class="n">mean</span><span class="p">())</span>
<span class="go">2.0</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">mx</span> <span class="o">-</span> <span class="n">mx</span><span class="o">.</span><span class="n">mean</span><span class="p">())</span>
<span class="go">[-2.0 -1.0 -- 1.0 2.0]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">mx</span><span class="o">.</span><span class="n">anom</span><span class="p">())</span>
<span class="go">[-2.0 -1.0 -- 1.0 2.0]</span>
</pre></div>
</div>
</div>
<div class="section" id="filling-in-the-missing-data">
<h2>Filling in the missing data<a class="headerlink" href="#filling-in-the-missing-data" title="Permalink to this headline">¶</a></h2>
<p>Suppose now that we wish to print that same data, but with the missing values
replaced by the average value.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">mx</span><span class="o">.</span><span class="n">filled</span><span class="p">(</span><span class="n">mx</span><span class="o">.</span><span class="n">mean</span><span class="p">()))</span>
<span class="go">[ 0.  1.  2.  3.  4.]</span>
</pre></div>
</div>
</div>
<div class="section" id="numerical-operations">
<h2>Numerical operations<a class="headerlink" href="#numerical-operations" title="Permalink to this headline">¶</a></h2>
<p>Numerical operations can be easily performed without worrying about missing
values, dividing by zero, square roots of negative numbers, etc.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">numpy.ma</span> <span class="k">as</span> <span class="nn">ma</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">1.</span><span class="p">,</span> <span class="o">-</span><span class="mf">1.</span><span class="p">,</span> <span class="mf">3.</span><span class="p">,</span> <span class="mf">4.</span><span class="p">,</span> <span class="mf">5.</span><span class="p">,</span> <span class="mf">6.</span><span class="p">],</span> <span class="n">mask</span><span class="o">=</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">y</span> <span class="o">=</span> <span class="n">ma</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">1.</span><span class="p">,</span> <span class="mf">2.</span><span class="p">,</span> <span class="mf">0.</span><span class="p">,</span> <span class="mf">4.</span><span class="p">,</span> <span class="mf">5.</span><span class="p">,</span> <span class="mf">6.</span><span class="p">],</span> <span class="n">mask</span><span class="o">=</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">ma</span><span class="o">.</span><span class="n">sqrt</span><span class="p">(</span><span class="n">x</span><span class="o">/</span><span class="n">y</span><span class="p">))</span>
<span class="go">[1.0 -- -- 1.0 -- --]</span>
</pre></div>
</div>
<p>Four values of the output are invalid: the first one comes from taking the
square root of a negative number, the second from the division by zero, and
the last two where the inputs were masked.</p>
</div>
<div class="section" id="ignoring-extreme-values">
<h2>Ignoring extreme values<a class="headerlink" href="#ignoring-extreme-values" title="Permalink to this headline">¶</a></h2>
<p>Let’s consider an array <code class="docutils literal notranslate"><span class="pre">d</span></code> of floats between 0 and 1. We wish to
compute the average of the values of <code class="docutils literal notranslate"><span class="pre">d</span></code> while ignoring any data outside
the range <code class="docutils literal notranslate"><span class="pre">[0.2,</span> <span class="pre">0.9]</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">d</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">linspace</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">20</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">d</span><span class="o">.</span><span class="n">mean</span><span class="p">()</span> <span class="o">-</span> <span class="n">ma</span><span class="o">.</span><span class="n">masked_outside</span><span class="p">(</span><span class="n">d</span><span class="p">,</span> <span class="mf">0.2</span><span class="p">,</span> <span class="mf">0.9</span><span class="p">)</span><span class="o">.</span><span class="n">mean</span><span class="p">())</span>
<span class="go">-0.05263157894736836</span>
</pre></div>
</div>
</div>
</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>